Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/t3_1/doc.lha/documentation/manual/kmp.notes.1to4

Text File | 1987-06-30 | 20KB | 469 lines

p1 "The symbol `===' ... means that for any x, the values and effects
    are the same as the values and effects of ..."

 Should some word like "defined" be modifying each of these "values
 and effects" phrases?

p4 "a core language --- syntax and semantics for expressions"

 At this point, you have not introduced the term expression. I think
 it's important to early-on make some sort of note about expressions
 being objects and not external syntactic representations. I don't
 think having the note about external representation above this is
 adequate. On the next page, you start to talk about forms and
 expressions as if people knew what they were. There may be a few
 who think expressions are parens and spaces and ... The ones who
 are bright but have just been misled should have the opportunity to
 get fixed somewhere in this part of the book. This is especially
 important since all your examples will necessarily be presented as
 external syntax.

p5 "Program execution typically occurs in an environment inferior to ..."

 You have not said that environments are hierarchical, so the wrong
 interpretation of "inferior" may come out here (the one that makes you
 think the system environment is somehow "more winning").

p5 Programs, Procedures, Functions

 Winston's book (latest draft) introduces the following terms (quoting):

      o A "procedure" is the basic entity in LISP that specifies
        how something is to be computed. A procedure may be defined
        by the user or provided by the LISP system.

      o A procedure (like +) supplied by LISP itself is called a "primitive".

      o A procedure that only computes a value based on its argument, is
        called a "function". Procedures are not functions if they have
        "side effects", such as assigning a value to a symbol other than
        one of the procedure's parameters.

      o A collection of procedures, intended to work together, is called
        a "program".

      o An abstract description of a procedure or program, one not
        expressed in a programming language, is called an algorithm.
        Such a description may, for example, be given in English or
        as a block diagram. A procedure or a program may be considered
        an implementation of  an algorithm in a particular programming
        language.

 I dislike this definition of "primitive". I question some of the wording in
 the description of "function" and "algorithm". But I think in general having
 a nice, clearly defined, repertoire of terms like this would be nice if it
 could be carried through.

 I also wish you would re-instate some of my terms like "universal" and
 perhaps even the term "span" (as in "PLUS? spans only the real numbers.").

 Also, something Winston doesn't do but which I plan to suggest is to mark
 clearly that these are not "the" definitions of the terms, but just the
 local conventions for use in the context of this document. Somewhere, there
 should be a clear diclaimer of the fact that other dialects use similar
 terms in incompatible and/or just-plain-muddy ways.

p7 Literals, examples

 I think I might put the equivalences in. It's amazing how many novices
 I've known who were surprised that

        (READ)''FOO => (QUOTE (QUOTE FOO))

 Hence, the second examples section might be written:

        (QUOTE A)     === 'A     => A
        (QUOTE (A B)) === '(A B) => (A B)
        ... etc


p7 "Objects returned by literal expressions are read-only..."

 I already mentioned to you that I question if this even says what you
 want but I'll note it here so it's all in one place.

 Also, I'm a little unsure of the term "read only" since you have not
 defined it and since in some contexts in computer science it is synonymous
 with "write protected". eg, Read-Only buffers in Emacs. You might want
 to say "intended to be read-only".

p8 "If variables is not a proper list ... the variable x will be ..."

 Why do I want to say "the variable named x will be ..."? Do you think
 that it matters? Something caught my eye about this wording which I am
 not sure how to resolve: Is the object which is the symbol the variable
 or is it the name of the variable or does it denote the name or does
 it co-denote the variable? Sigh.

p8 "If any <variable> is () instead of ..."

 I don't like this wording. Just about anything would be an improvement.
 For example, I might prefer
   "If any element of <variables> is ..."
 or
   "If in place of a variable, there is a () in the <variables> list, ..."
 Anything that does not seem to imply "()" is a variable. I realize the
 name <variable> here is a formal term, but it still feels funny; especially
 since () === NIL in other dialects and hence -is- a variable.

 Also, I think an example would help a lot.

p8 "Scoping: ..."

 An example would help. Perhaps:

        (LSET X 3)
        (DEFINE (FOO Y) (+ X Y))
        (DEFINE (G X) (+ X (FOO X)))
        (G 4) => 11 ;not 12

p8 "Closure: ..."

 I would add an example here, too. Perhaps:

        (DEFINE (ADDER X) (LAMBDA (Y) (+ X Y)))
        ((ADDER 5) 3) => 8
        (DEFINE ADD5 (ADDER 5))
        (DEFINE (TESTER X) (ADD5 (- X 5)))
        (TESTER 7) => 7

p8 "There is no way (other than EQ?) ..."

 This is technically false. For example,

  (DEFINE (MY-EQ? X Y) ;Things that have EQ? built in
    (WITHOUT-INTERRUPTS
      (= (OBJECT-HASH X) (OBJECT-HASH Y))))

  or (DEFINE (MY-EQ? X Y) (MEMQ? X (LIST Y)))

  or (DEFINE (MY-EQ? X Y) (NOT (NEQ? X Y)))

  or even...

  (DEFINE MY-EQ? (L1 L2) ;GJS's paint-X-and-see-if-Y's-color-changes approach
    (WITHOUT-INTERRUPTS
      (COND ((NOT (EQUAL? (CAR L1) (CAR L2))) NIL)
            (ELSE
             (LET ((MARKER (IF (EQUAL? (CAR X) 'MARKER-1) 'MARKER-2
                             'MARKER-1))
                   (CAR-L1 (CAR L1)))
               (UNWIND-PROTECT (PROGN (SET (CAR L1) MARKER)
                                      (EQUAL? (CAR L1) MARKER))
                 (SET (CAR L1) CAR-L1)))))))

 I guess my point is that if EQ? were the only way to tell the difference,
 this wouldn't matter. But, in fact, EQ? is the only primitive which directly
 does just that thing, but it is hardly the only way to tell. In fact, if
 the only importance of object identity was that EQ? answered true, then
 it would be worthless. A lot is implied by this fact.

 I believe what you're trying to say here is OK; important, in fact.
 I just don't think you are saying what you mean to say.

p9 "Uniqueness of symbols is defined..."

 The "(EQ? 'FOO 'FOO) => true" example is interesting but I am not sure
 its implications will be seen to the untrained eye. Perhaps. Could I
 con you into elaborating on the meaning of "uniqueness" and/or "interning"
 (for symbols AND for more general data) either here or someplace else? It
 is an interesting topic and worth of inclusion someplace.

p9 "There is one false value; this is a distinguished object called <null>."

 First of all, you call it <false> afterward, so it's a little funny that
 you claim here its name is <null>.

 Second of all, I think it's not a good idea to give the false/null
 confusion such good placement. IN FACT, I would (as with plists of
 symbols) just mark this relation as a bug in implementations and
 write the manual as if it didn't have to be true. People will balk
 a little but as long as you don't actually change the implementation,
 they'll probably let you get that far. Then, maybe later after the
 manual has been made it crystal clear, one day things could magically
 be righted ... or in the worst case, at least the language spec would
 be pure even if the implementation was not...

p9 "A value intended to be used in this way is called a truth value."

 This sentence is ambiguous. My first reading took the reference to be
 to the previous sentence ("Any other value is considered to be true."),
 but I couldn't believe you meant "truth value" and "true value" to be
 synonymous. If you mean for it to span both "true" and "false" values,
 you must be more clear than just "in this way".

p9 "... usually involve a test expression ..."

 "test" would be another good glossary word. There should be a glossary
 of useful terms. "test" denotes an expression, "predicate" a function.
 I like this. LispM calls a test a "pred" in most of the relevant arglists.
 This drives me batty. Standardizing terminology encourages better
 user-programming style for people who aren't handy with the thesaurus.

p9 "... equality predicate is a two-argument predicate which is
    side-effectless and unaffected by side-effects, and ..."

 By this definition, EQUAL? is not an equality predicate.

 Further, the implication seems to be that predicates which are not
 for equality (eg, PLUS?, PRIME?, ...) should be allowed to have
 side-effects?

 Are you sure you don't want the "is side-effectless" over predicates
 in general?

 Are you sure you don't want to rethink "not affected by side-effect"?
 At the heart of this is that presumably you mean that for the same
 arguments, equality predicates always return the same value even in
 the face of side-effect; yet "sameness of argument" is something you
 can't tell without presupposing you have the predicate you're trying
 to define sometimes... Such is the case, at least, for EQUAL?

p10 "The system variable T ..."

 You might want a "(Programmers with prior LISP experience ...)" note
 about how (EQ? T 'T) is not necessarily true. T and 'T are used
 interchangeably in some dialects. If you don't think it's worth the
 space or bother, I won't insist.

p10 "Types"

 Objects don't have behaviors (except in the T sense of OBJECT, which
 is not what I think you mean); functions have behaviors given object
 arguments. There was some definition I've heard for types which said
 that it was sufficient to think of an object as being of a given type
 if for all functions defined upon that type, the behavior of those
 functions was well-defined. Or something like that. More simply put,
 that a type was just a way of describing a set of things upon which you
 wanted to do a certain operation or set of operations. Anyway, these
 are just ideas. My main point here is that I think the idea of
 "characteristic behaviors" is either too vague or too mathematical
 or both or neither. I would prefer something slightly less cryptic.

 Interestingly, when you mention type predicates, you neglect to mention
 that by convention they return true for things said to be of a certain
 type and false otherwise. I imagine people will guess that, and in
 principle it might not matter, but it might be worth mentioning as a
 point of formality.

p11 "Environments ... on entering LAMBDA-bodies"

 I would say "upon".

p11 "One such association ... is called a <binding>."

 I would say "Abstractly, one such association ..." or something to
 qualify that there is no first class object in the user world
 which corresponds to this pair. Alternate wording:
  "Viewed abstractly, an environment is made up of a set of pairs.
   Each pair, called a binding, represents an association between
   a variable and a value in that environment. In general, environments
   are created implicitly...etc."

p11 "Each contour augments an ``outer'' ..."

 Parallel construction; since you haven't said "Each inner contour",
 it seems funny.

 Also, "a few" is pretty funny since it might mean zero.

 Perhaps:
  "A new contour is always created ``inside of'' some existing contour.
   A new contour augments its ``parent'' or ``outer'' contour by
   providing bindings for any new identifiers..."

p11 "The values of BLOCK and LAMBDA ... they are reserved words..."

 Will have to change now that you've backed down about reservedness.

p11 "... in an outermost environment in which the variable LIST is bound."

 Outermost? I would prefer "outer", which means rewording. eg,

  "The variable LIST is presumably bound in some outer environment."

 You might add "(such as the initial environment)" or "...standard..."
 if you think the "outer environment" needs qualification of some sort.

p11 "There are two kinds of contours, <lambda-contours> and <locales>..."

 I would ammend parts of this paragraph such that you say something like:
   "Lambda contours, such as those explained above, are introduced by ..."
 and
   "Locales, to be explained later, are introduced by ..."
 to avoid any possible feeling that this page is sufficient to understand
 the two kinds.

p11 "...where the variables are bound to those values..."

 "...where each of the variables is bound to its {associated/respective}
     value..."

p12 LET*

 This introduces the concept of "sequential binding" without introducing
 it as a technical term. Put this and "parallel binding" on my glossary
 wish-list. I have run into people from time to time who object to the
 terms "parallel" and "sequential" since in fact all binding is sequential
 in certain ways and certainly on a single-processor machine, parallel
 anything is a bit difficult to grasp. I like the terms "sequential" and
 "parallel" here, but I think it important to at least qualify them.

p12 "LABELS is useful for defining procedures that may be"

 I would say "... which may be ..."

p12 "... where all of the variables are bound to those values ..."

 "... where each of the variables is bound to its respective value ..."

p13 "... However, the values of the variables are not defined until body ..."

 Something like:
 "Although the evaluation of the <values> takes place in an environment
  where all of the <variables> are bound, the actual values of the
  <variables> do not become well-defined until the body is entered.
  Hence, the <value> forms may close over any of the <variables> for
  later use, but may not directly access the contents of any of the
  <variables>."
 Reason:
  It is worth adding a little redundancy about the difference between
  saying a binding is in effect and saying a variable has a well-defined
  value. Also, I think the statement about not "using" <variables> is too
  nebulous.
 Note: If you use a description such as the one I suggest, the phrase
  "closed over" should be entered in the glossary.

p13 "==="
                      ~
 Have you considered "=" (two bars with tilde above) to denote a weaker
 kind of slightly assymetric equivalence meaning "can be implemented by"?

p14 "Locales serve two purposes..."

 I don't think this opening paragraph is sufficiently motivational.
 It doesn't give you a good reason for wanting to read the section other
 than just that it mystifies you and that you therefore have no choice.

 I would rather it be something along the lines of:

   "A locale is a mutable binding contour which serves as a bounding
    point for `free' references."

 I also like the phrase "locally global contour" if you can work it in.
 Making analogy to a filesystem "working directory" might be handy, too.

 In any case, the main thing is that the first paragraph in a section like
 this should be more abstract than technical. The first paragraph as it
 is written here contains important and useful info, but it should not come
 first.

 If paragraph 2 were reworked and moved above paragraph 1, I would be
 satisfied on this point.

p14 "Introduces a locale..."

 I think of the verb "introduce" as meaning a declarative form that
 precedes the thing it introduces. Eg, (DECLARE ...) at the top of a
 lambda contour or the FOR statement in basic. Since LOCALE goes around
 the contour it introduces, I feel funny about saying it "introduces".
 Can you think of another verb? Would "establishes" or "creates" or
 "instantiates" work?

p14 "Introduces a locale ... If <variable> is () ..."

 I again take issue with saying () can be a variable, which is what this
 reads like. I would call the cadr of a LOCALE form <spec> and say
 it may be either a variable or ().

 By the way, it's an incompatible change (which could be made upward
 compatibly in one release and then cleaned up in a later release), but
 I wonder if it shouldn't be (LOCALE (var) ...) or (LOCALE () ...) just
 to alleviate this wording problem and also to motivate the () better.
 After all, I always wonder why it's not just any non-symbol that works.
 Have I complained about this before? I seem to remember I might have...

p14 "(DEFINE variable value) -> undefined"

 I find it amusing that DEFINE yields an undefined value. At first glance,
 this should seem counterintuitive.

p14 "The variable is given <value> as its value.
     The second DEFINE syntax is for defining procedures."

 I dunno, but I have the subtle impression this biases people just
 slightly toward thinking you have to use the second syntax for
 procedures (even though the next example ought to fix that). People
 frequently skim and miss that sort of thing. I would make it more
 apparent as in:

  "In the simple syntax, the variable is simply given <value> as its value.

   The second syntax just provides ``syntactic sugar'' for the
   common case of defining a variable to hold a function.
   Using the second syntax,
        (DEFINE <variable> (LAMBDA <arguments> . <body>))
   may written as simply:
        (DEFINE (<variable> . <arguments>) . <body>)"

p14 "LSET is identical to DEFINE except that the procedure definition
     is not permitted, and the variable is declared ..."

 This makes it sound like it fell naturally out of the code, but you are
 being nasty and forcing the user to write the long syntax. (Of course, the
 thing I'm going to propose as an alternative will sound like you were
 just too lazy to write the code so he could write the short syntax. The
 real idea that should come through in some subtle way is that the
 second DEFINE syntax is superfluous since you rarely need it anyway.)
 I would say:

        "LSET is identical to the simple case of DEFINE, except that the
         variable is declared to be alterable."

 or at least just

        "LSET is identical to DEFINE except that the variable is
         declared to be alterable."


p14 "Any LOCALE-expression ..."

 Do you really use the syntax "FOO-expression" a lot? I haven't noticed
 it until just now. I don't like the hyphen. Also, I prefer the word "form"
 rather than "expression", especially  when the car does not denote a subr.

 In any case, I might revamp the last sentence as follows:

   "Cases may arise where LABELS or LET could be rewritten using LOCALE
    (or vice versa). It may vary with the context whether a given choice
    makes code easier or harder to read or manipulate."

p15 "... *DEFINE or *LSET ..."

 This should make some sort of (possibly casual and fleeting) reference
 to the fact that such calls may be either explicit or implicit. I wouldn't
 dwell on it, but I think it might not hurt to at least mention.
 eg, I presume you can instantiate a locale as your working environment,
 in which case you wouldn't write *DEFINE explicitly.
 Also, I presume IMPORT calls these guys implicitly.

p15 "References in a LOCALE body to variables bound later on ..."

 You should be clearer about this. Obviously,
  (LOCALE () (DEFINE (FOO) (BAR)) (DEFINE (BAR) ...))
 works (doesn't it?).

 Should some of this warning be in the form of a "bug" note rather
 than a language spec issue?

p16 *LSET

 I dunno about "creates a binding". I know the meaning of "binding" you
 mean here, but I would check through the manual to make sure this term
 is consistently used. It's a good glossary term anyway, but you might want
 to point out it has more than one usage. I suppose this will be easier when
 BIND has been renamed. I might say something like:
  "Creates an association between <identifier> and <value> in the given
   <locale>, such that a later *VALUE access to the given <identifier>
   in that <locale> will yield <value>."